JSON Serialization Improvements #936

Gerrit0 · 2019-01-02T22:23:39Z

This is a rework of the JSON serialization, completing the work done in #597 and removing the deprecated .toObject methods.

The JSON schema retains the old structure, which is now described by the JSONOutput namespace.

closes #930
closes #728
closes #605

Also update tests to correctly use the serializer - it wasn't tested before.

See microsoft/TypeScript#18877

aciccarello

Thanks for cleaning out the duplicated code. I would like to see if we can simplify this.

aciccarello · 2019-05-18T02:29:53Z

src/lib/serialization/schema.ts

+ *
+ * For documentation on the JSON output properties, view the corresponding model.
+ */
+export namespace JSONOutput {


What is the motivation to have this as a namespace? Should we have a top level model exporting these (i.e. typedoc/serialization)?

I believe my idea was to avoid polluting the global scope with ~40 new types.

The new top level export makes sense, but I think the way to do it should probably be to not publish TypeDoc within the dist/lib folder, this would be a massive breaking change, since basically all plugins import the Component decorator from typedoc/dist/lib/...

I've moved these out of the namespace, there was no need as avoiding the pollution could be done by re-exporting under a specific name later. I still think the typedoc/serialization module is a good idea, but again, breaking changes that don't need to happen yet & should be thought through carefully.

aciccarello · 2019-05-18T02:48:58Z

src/lib/serialization/schema.ts

+ */
+export type ModelToObject<T> = T extends Array<infer U> ? _ModelToObject<U>[] : _ModelToObject<T>;
+
+// Order matters here. Some types are subtypes of other types.


That's an important note. Thanks for calling it out.

I was hoping that we could have some type of keyof mapping that might be simpler but it doesn't sound like that's possible.

With some changes to the JSON output, it would be possible, but for the initial typing I decided to just maintain the existing output types.

aciccarello · 2019-05-18T02:54:16Z

src/lib/models/reflections/container.ts

-     * Return a raw object representation of this reflection.
-     * @deprecated Use serializers instead
-     */
-    toObject(): any {


Is it possible to stub this with a call to the real serializer? This would help those who are looking for the serializer on the ProjectReflection.

It is possible, yes, but I'm not sure it is a good idea. To make it work we have 2 options.

Construct a new serializer whenever .toObject is called

Add an application: Application property to every reflection so that it can access the real serializer.

There are problems with both.

The new serializer will be missing any extra serializers added by plugins

Requires changing every reflection, and reflections really shouldn't know about serializers anyways (at least, that's the theory with having separate serialization...)

Since .toObject has been deprecated for nearly 2 years, I feel pretty ok about just removing the method.

aciccarello · 2019-05-18T02:55:17Z

src/lib/serialization/schema.ts

+        title: M.ReflectionGroup['title'];
+        kind: M.ReflectionGroup['kind'];
+        children?: M.ReflectionGroup['children'][number]['id'][];
+        categories?: ModelToObject<M.ReflectionGroup['categories']>;


Would it make sense to move these interfaces to the individual serializers?

Yes, it absolutely makes sense 👍 Will do.

Coming back to this, I'm not sure it does make sense. It's still an option, but having all the types in one place lets us avoid importing the S helper I introduced to resolve another of your comments everywhere (and thus keeps that particular bit of ugly out of the rest of of the code)

On the other hand, it would be nice to have the types closer to the code that produces values of that type...

aciccarello · 2019-05-18T03:25:50Z

src/lib/serialization/schema.ts

+        type?: ModelToObject<M.SignatureReflection['implementationOf']>;
+        overwrites?: ModelToObject<M.SignatureReflection['implementationOf']>;
+        inheritedFrom?: ModelToObject<M.SignatureReflection['implementationOf']>;
+        implementationOf?: ModelToObject<M.SignatureReflection['implementationOf']>;


Many of these look like they could be simplified using a keyof mapping.

Something like

type SignatureReflection = SimpleSerialization<Reflection>

This would help avoid issues when refactoring property names.

How did I miss the names here... I was avoiding keyof since for some reflections, not all properties are exported (notably, parent is absent as JSON can't include circular data structures)

Also, while it is certainly possible to use Exclude on the keyof result, this results in types which are displayed in a much less user friendly manner. The redundancy hurts, but I think it is probably worth it for types that can be easily explored.

If we have common patterns (like parent) there should be a way to exclude that.

I gave this a shot, looking into preventing specific properties from being serialized and I don't think it is the right way to go about this.

The list changes for (almost) every serialized reflection.

As soon as a new property is added to a reflection, the serializer types have to be updated, even though nothing changed there.

Instead I introduced a helper S local to this file that handles basic cases. It behaves similarly to Pick, but passes properties through ModelToObject if necessary. Thoughts?

…ix/serializer-plugin

It did nothing more than Assert.deepStrictEqual, since if the objects weren't exactly the same deepEqual would throw.

- Move JSON types out of the namespace - Introduce a helper to semi-automatically conver types to their JSON equivalent - Address all the build errors caused by removing the namespace

Gerrit0 added 8 commits December 31, 2018 16:37

Remove deprecated toObject methods

95238ff

Also update tests to correctly use the serializer - it wasn't tested before.

2 spaces -> 4 spaces

7fc3f5b

Remove the unnecessary serializeGroupSymbol

ac20649

Strongly type the JSON output

5f497d8

Improve serialization types

461315b

Export JSON schema

56ed79c

Update declaration merging instructions

1146c3f

See microsoft/TypeScript#18877

Correct spec rebuild script

b7f570e

jonchardy mentioned this pull request Jan 14, 2019

Category improvements #938

Merged

Gerrit0 and others added 8 commits May 8, 2019 16:44

Merge branch 'master' into fix/serializer-plugin

d3d15d9

Update serialization types to with category changes

fb3eef4

Remove @component from serializers

39ad773

Fix compiler errors

b353c4d

Clean up imports

555c66d

Fix tests

4e50da9

[ci skip] Fix rebuild spec script

1dad162

Merge branch 'master' into fix/serializer-plugin

04431d0

aciccarello requested changes May 18, 2019

View reviewed changes

Gerrit0 added 4 commits October 13, 2019 13:22

Merge branch 'master' of https://github.com/TypeStrong/typedoc into f…

2f40761

…ix/serializer-plugin

Fix build errors

66ddd00

Remove unnecessary compareReflections

f5b5837

It did nothing more than Assert.deepStrictEqual, since if the objects weren't exactly the same deepEqual would throw.

Address PR comments

5a2fac6

- Move JSON types out of the namespace - Introduce a helper to semi-automatically conver types to their JSON equivalent - Address all the build errors caused by removing the namespace

Gerrit0 mentioned this pull request Nov 1, 2019

Documentation for generated json file --json #1125

Closed

Gerrit0 added this to the 0.16.0 milestone Nov 3, 2019

Gerrit0 mentioned this pull request Dec 6, 2019

question: Is there a spec documenting the json format? #1145

Closed

Gerrit0 mentioned this pull request Jan 11, 2020

feat: Support for export declarations #1157

Merged

Gerrit0 merged commit 5a2fac6 into master Jan 12, 2020

Gerrit0 deleted the fix/serializer-plugin branch January 14, 2020 20:05

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

JSON Serialization Improvements #936

JSON Serialization Improvements #936

Gerrit0 commented Jan 2, 2019

aciccarello left a comment

aciccarello May 18, 2019

Gerrit0 May 18, 2019

Gerrit0 Oct 14, 2019

aciccarello May 18, 2019

Gerrit0 May 18, 2019

aciccarello May 18, 2019

Gerrit0 May 18, 2019

aciccarello May 18, 2019

Gerrit0 May 18, 2019

Gerrit0 Oct 14, 2019

aciccarello May 18, 2019

Gerrit0 May 18, 2019

Gerrit0 May 18, 2019

aciccarello May 18, 2019

Gerrit0 Oct 14, 2019

JSON Serialization Improvements #936

JSON Serialization Improvements #936

Conversation

Gerrit0 commented Jan 2, 2019

aciccarello left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment